<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>RVM : Configuring the RVM</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            RVM : Configuring the RVM
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Apr 26, 2007 by <font color="#0050B2">pdonald</font>.
				    </div>

				    <p>The build process requires a number of build time parameters that specify the features and components for a Jikes RVM build. Typically the build parameters are defined within a property file located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/configs/">build/configs</a> directory. The following table defines the parameters for the build configuration.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Default </th>
</tr>
<tr>
<td class='confluenceTd'> config.name </td>
<td class='confluenceTd'> A unique name that identifies the set of build parameters. </td>
<td class='confluenceTd'> None </td>
</tr>
<tr>
<td class='confluenceTd'> config.bootimage.compiler </td>
<td class='confluenceTd'> Parameter selects the compiler used when creating the bootimage. Must be either <em>opt</em> or <em>base</em>. </td>
<td class='confluenceTd'> base </td>
</tr>
<tr>
<td class='confluenceTd'> config.bootimage.compiler.args </td>
<td class='confluenceTd'> Parameter specifies any extra args that are passed to the bootimage compiler. </td>
<td class='confluenceTd'> "" </td>
</tr>
<tr>
<td class='confluenceTd'> config.runtime.compiler </td>
<td class='confluenceTd'> Parameter selects the compiler used at runtime. Must be either <em>opt</em> or <em>base</em>. </td>
<td class='confluenceTd'> base </td>
</tr>
<tr>
<td class='confluenceTd'> config.include.aos </td>
<td class='confluenceTd'> Include the adaptive system if set to true. Parameter will be ignored if config.runtime.compiler is not <em>opt</em>. </td>
<td class='confluenceTd'> false </td>
</tr>
<tr>
<td class='confluenceTd'> config.assertions </td>
<td class='confluenceTd'> Parameter specifies the level of assertions in the code base. Must be one of <em>extreme</em>, <em>normal</em> or <em>none</em>. </td>
<td class='confluenceTd'> normal </td>
</tr>
<tr>
<td class='confluenceTd'> config.include.all-classes </td>
<td class='confluenceTd'> Include all the Jikes RVM classes in the bootimage if set to true. </td>
<td class='confluenceTd'> false </td>
</tr>
<tr>
<td class='confluenceTd'> config.default-heapsize.initial </td>
<td class='confluenceTd'> Parameter specifying the default initial heap size in MB. </td>
<td class='confluenceTd'> 20 </td>
</tr>
<tr>
<td class='confluenceTd'> config.default-heapsize.maximum </td>
<td class='confluenceTd'> Parameter specifying the default maximum heap size in MB. </td>
<td class='confluenceTd'> 100 </td>
</tr>
<tr>
<td class='confluenceTd'> config.include.gcspy </td>
<td class='confluenceTd'> Set to true to build RVM with GCSpy support. See <a href="Using GCSpy.html" title="Using GCSpy">Using GCSpy</a> for more details. </td>
<td class='confluenceTd'> false </td>
</tr>
<tr>
<td class='confluenceTd'> config.include.gcspy-client </td>
<td class='confluenceTd'> Set to true to bundle the GCSpy client with the Jikes RVM build. Parameter will be ignored if config.include.gcspy is not <em>true</em>. </td>
<td class='confluenceTd'> false </td>
</tr>
<tr>
<td class='confluenceTd'> config.include.gcspy-stub </td>
<td class='confluenceTd'> Set to true to use the GCSpy stub rather than the real GCSpy component. Parameter will be ignored if config.include.gcspy is not <em>true</em>. </td>
<td class='confluenceTd'> false </td>
</tr>
<tr>
<td class='confluenceTd'> config.stress-gc-interval </td>
<td class='confluenceTd'> The build will stress test the gc subsytem if set to a positive value. The value indicates the number of allocations between collections </td>
<td class='confluenceTd'> 0 </td>
</tr>
<tr>
<td class='confluenceTd'> config.mmtk.plan </td>
<td class='confluenceTd'> The name of the GC plan to use for the build. See <a href="MMTk.html" title="MMTk">MMTk</a> for more details. </td>
<td class='confluenceTd'> None </td>
</tr>
</tbody></table>

<h2><a name="ConfiguringtheRVM-JikesRVMConfigurations"></a>Jikes RVM Configurations</h2>

<p>A typical user will use one of the existing build configurations and thus the build system only requires that the user specify the config.name property. The name should match one of the files located in the build/configs/ directory minus the '<tt>.properties</tt>' extension.</p>

<h3><a name="ConfiguringtheRVM-LogicalConfigurations"></a>Logical Configurations</h3>

<p>There are many possible Jikes RVM configurations. Therefore, we define four "logical" configurations that are most suitable for casual or novice users of the system.  The four configurations are: </p>

<ul>
	<li><b>prototype:</b> A simple, fast to build, but low performance configuration of Jikes RVM.  This configuration does not include the optimizing compiler or adaptive system.  Most useful for rapid prototyping of the core virtual machine.</li>
	<li><b>prototype-opt:</b> A simple, fast to build, but low performance configuration of Jikes RVM.  Unlike prototype, this configuration does include the optimizing compiler and adaptive system. Most useful for rapid prototyping of the core virtual machine, adaptive system, and optimizing compiler.</li>
	<li><b>development:</b> A fully functional configuration of Jikes RVM with reasonable performance that includes the adaptive system and optimizing compiler.  This configuration takes longer to build than the two prototype configurations.</li>
	<li><b>production:</b> The same as the development configuration, except all assertions are disabled.  This is the highest performance configuration of Jikes RVM and is the one to use for benchmarking and performance analysis. Build times are similar to the development configuration.</li>
</ul>


<p>The mapping of logical to actual configurations may vary from release to release.  In particular, it is expected that the choice of garbage collector for these logical configurations may be different as MMTk evolves.</p>

<h3><a name="ConfiguringtheRVM-ConfigurationsinDepth"></a>Configurations in Depth</h3>

<p>Most standard Jikes RVM configuration files loosely follow the following naming scheme:</p>

<p><em>&lt;boot image compiler&gt;</em> <b><tt>Base</tt>"<em>&#124;</em>"<tt>Adaptive</tt>"</b> <em>&lt;garbage collector&gt;</em><br/>
where</p>
<ul>
	<li>the <em>&lt;boot image compiler&gt;</em> is the compiler used to compile Jikes RVM's boot image.</li>
	<li><b><tt>Base</tt>"<em>&#124;</em>"<tt>Adaptive</tt>"</b> denotes whether or not the adaptive system and optimizing compiler are included in the build.</li>
	<li>the <em>garbage collector</em> is the garbage collection scheme used.</li>
</ul>


<p>The following garbage collection suffixes are available:</p>
<ul>
	<li>"NoGC" no garbage collection is performed.</li>
	<li>"SemiSpace" a copying semi-space collector.</li>
	<li>"MarkSweep" a mark-and-sweep (non copying) collector</li>
	<li>"GenCopy" a classic copying generational collector with a copying higher generation</li>
	<li>"GenMS" a copying generational collector with a non-copying mark-and-sweep mature space</li>
	<li>"CopyMS" a hybrid non-generational collector with a copying space (into which all allocation goes), and a non-copying space into which   survivors go.</li>
	<li>"RefCount" a reference counting collector with synchronous (non-concurrent) cycle collection</li>
</ul>



<p>For example, to specify a Jikes RVM configuration:</p>
<ol>
	<li>with a baseline-compiled boot image,</li>
	<li>that will compile classes loaded at runtime using the baseline compiler and</li>
	<li>that uses a non-generational semi-space copying garbage collector,</li>
</ol>


<p>use the name <b>"<tt>BaseBaseSemiSpace</tt>"</b>.</p>

<p>Some files augment the standard configurations as follows:</p>
<ul>
	<li>The word <b>"<tt>Full</tt>"</b> at the beginning of the configuration name identifies a configuration such that all the Jikes RVM classes are included in the boot image. (By default  only a small subset of these classes are included in the boot image.)</li>
	<li><b>"<tt>FullAdaptive</tt>"</b> images have all of the included classes already compiled by the optimizing compiler.</li>
	<li><b>"<tt>FullBaseAdaptive</tt>"</b> images have the included classes already compiled by the baseline compiler; the adaptive system will later recompile any hot methods.</li>
	<li>The word <b>"<tt>Fast</tt>"</b> at the beginning of  the configuration name identifies a <b>"<tt>Full</tt>"</b> configuration where all assertion checking has been turned off. Note: <b>"<tt>Full</tt>"</b> and <b>"<tt>Fast</tt>"</b> boot images run faster but take longer to build.</li>
	<li>Prefixing the configuration with <b>"<tt>ExtremeAssertions</tt>"</b> indicate that the <tt>config.assertions</tt> configuration parameter is set to <tt>extreme</tt>. This turns on a number of expensive assertions.</li>
</ul>



<p>In configurations that include the adaptive system (denoted by <b>"<tt>Adaptive</tt>"</b> in their name), methods are initially compiled by one compiler (by default the baseline compiler) and then online profiling is used to automatically select hot methods for recompilation by the optimizing compiler at an appropriate optimization level.</p>

<p>For example, to a build for an adaptive configuration, where the optimizing compiler is used to compile the boot image and the semi-space garbage collector is used, use the following command:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>% ant -Dconfig.name=OptAdaptiveSemiSpace
</pre>
</div></div>


				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
		    </tr>
	    </table>
    </body>
</html>